package 基础;

Java - 文档(Documentation)
Scan me!
Java语言支持三种类型的注释 -

1. /* text */ 编译器忽略从/ *到* /的所有内容。

2. //text  编译器会忽略从//到行尾的所有内容。

3. /** documentation */  这是一个文档注释，通常称为doc comment 。 JDK javadoc工具在准备自动生成的文档时使用doc comments 。

本章是关于解释Javadoc的。 我们将看到如何利用Javadoc为Java代码生成有用的文档。

什么是Javadoc？
Javadoc是一个JDK附带的工具，它用于从Java源代码生成HTML格式的Java代码文档，这需要以预定义格式的文档。

以下是一个简单的示例，其中/*....*/中的行是Java多行注释。 同样，//之前的行是Java单行注释。

例子 (Example)
/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {
   public static void main(String[] args) {
      /* Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

您可以在描述部分中包含必需的HTML标记。 例如，以下示例使用

.... h1>作为标题，
用于创建段落 -

例子 (Example)
/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {
   public static void main(String[] args) {
      /* Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

javadoc标签
javadoc工具识别以下标记 -

标签             描述                                                      句法
@author	       添加类的作者。                                            @author name-text
{@code}        以代码字体显示文本而不将文本解释为HTML标记或嵌套的javadoc标记。    {@code text}
{@docRoot}     表示从任何生成的页面生成的文档的根目录的相对路径。                 {@docRoot}
@deprecated    添加注释，指示不再使用此API。                                @deprecated deprecatedtext
@exception     使用类名和描述文本向生成的文档添加“ Throws子标题。               @exception类名描述
{@inheritDoc}  从nearest可继承类或可实现的接口继承注释。	继承来自直接超类的注释。
{@link}        插入带有可见文本标签的内嵌链接，该链接指向引用类的指定包，类或成员名称的文档。	{@link package.class＃member label}
{@linkplain}   与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。                {@linkplain package.class＃member label}
@param         将具有指定参数名称的参数后跟指定描述添加到“参数”部分。                    @param参数名称描述
@return        添加带有描述文本的“返回”部分。                                      @return描述
@see           添加“另请参见”标题，其中包含指向引用的链接或文本条目。                    @see参考
@serial        用于默认可序列化字段的doc注释中。                                    @serial字段描述| 包括| 排除
@serialData    记录writeObject（）或writeExternal（）方法写入的数据。               @serialData数据描述
@serialField   Documents an ObjectStreamField component.                    @serialField field-name字段类型字段描述
@since         使用指定的自动文本向生成的文档添加“Since”标题。                        @since发布
@throws        @throws和@exception标签是同义词。                                @throws类名描述
{@value}       在静态字段的doc注释中使用{@value}时，它会显示该常量的值。               {@value package.class #field}
@version       使用-version选项时，将指定版本文本的“版本”子标题添加到生成的文档中。       @version版本文本

例子 (Example)
以下程序使用了几个可用于文档注释的重要标记。 您可以根据自己的要求使用其他标签。

有关AddNum类的文档将在HTML文件AddNum.html中生成，但同时也将创建名为index.html的主文件。

import java.io.*;
/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }
   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */
   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);
      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

现在，使用javadoc实用程序处理上面的AddNum.java文件，如下所示 -

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: warning - @return tag cannot be used in method with void return type.
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
1 warning
$

您可以在此处查看所有生成的文档 - AddNum 。 如果您使用的是JDK 1.7，那么javadoc不会生成很好的stylesheet.css ，


《javadoc注释规范》

javadoc注释规范就是指文档注释，包括类、接口、方法、属性等的说明，在一个团队项目开发中，统一规范的注释很重要，对于自己以后的查看源码也极有帮助，如果没有
相应的注释，那么给团队合作、自己查看源代码都会带来非常大的工作量。

而且需要了解的是，java doc编译生成的文档是html格式的，所以，我们就得遵循一些规范，不至于生成的文档杂乱无章。

要注意的是，生成的文档是 HTML 格式，而这些 HTML 格式的标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。比如，需要换行时，不是敲入一个回车
符，而是写入 ＜br＞，如果要分段，就应该在段前写入 ＜p＞。  

  因此，格式化文档，就是在文档注释中添加相应的 HTML 标识。  

  文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如 
  /** 
   * This is first line. ＜br＞ 
   ***** This is second line. ＜br＞ This is third line. 
   */  

  编译输出后的 HTML 源码则是 This is first line. ＜br＞ This is second line. ＜br＞ This is third line.   

  前导的 * 号允许连续使用多个，其效果和使用一个 * 号一样，但多个 * 号前不能有其它字符分隔，否则分隔符及后面的 * 号都将作为文档的内容。

那么，哪些地方需要写注释？

《基本注释》

（1）类和接口
（2）构造方法
（3）普通方法（实体类对象的setter、getter方法不用注释）
（4）全局变量
（5）字段、属性

《特殊注释》

（1）典型算法
（2）在代码不明晰处
（3）在代码修改处加上修改标识注释
（4）在循环和逻辑分支组成的代码中注释
（5）为他人提供的接口必须详细注释

《注释的格式、类型》

单行注释：//……
块注释：/*……*/
文档注释：/**……*/

而javadoc，顾名思义，则是更多的是针对文档注释，本文也将大部分讲文档注释的java规范，那么，我们首先要了解，javadoc里的标记

 

Tag & Parameter          Usage                             Applies to                          Since
@author name             Describes an author.
                         描述作者                            Class, Interface	 
@version version	     Provides version entry. Max one per Class or Interface.
                         版本条目，每个类或接口最多有一个	      Class, Interface	 
@since since-text	     Describes since when this functionality has existed.
                         描述这个功能块从何时有的                Class, Interface, Field, Method	 
@see reference           Provides a link to other element of documentation.
                         提供链接到其他文档元素的链接             Class, Interface, Field, Method	 
@param name description	 Describes a method parameter.
                         描述一个参数                         Method	 
@return description	     Describes the return value.
                         描述返回值                          Method	 
@exception classname description
@throws classname description	Describes an exception that may be thrown from this method.
                         描述该方法可能抛出的异常                Method	 
@deprecated description	Describes an outdated method.
                         描述一个过期的方法                     Method	 
{@inheritDoc}            Copies the description from the overridden method.
                         从复写方法出拷贝来得描述                Overriding Method	                 1.4.0
{@link reference}        Link to other symbol.
                         连到其他的引用                       Class, Interface, Field, Method	 
{@value}                 Return the value of a static field.
                         返回一个静态作用域的值                 Static Field                           1.4.0

 
下面为参考举例，可在eclipse或myeclipse中设置模板，下文有介绍（注释一定要紧跟者类、方法、属性）

1、类和接口的注释
/**
 * 
 * @ClassName Test_Singleton.java
 * @Description TODO
 * @Author 先
 * @Time 2017年3月25日 下午3:12:43
 *
 */
public class Test {
    //……
}

2、构造方法的注释
/**
 * 
 * @Title: Test
 * @Description: TODO
 */
public Test(){
		
}

3、方法的注释
/**
 * 
 * @Title: test
 * @Description: TODO
 * @param para1
 * @param para2
 * @return String
 */
public String test(Integer para1,String para2){
	return para2;
}

4、属性、字段、全局变量的注释
/**
 * (说明内容)
 */
private String name;
/**
 * (说明内容)
 */
private final Integer id;

一些标记的相关使用说明

1、@see
@see 的句法有三种： 
?7?5@see 类名  
?7?5@see #方法名或属性名
?7?5@see 类名#方法名或属性名

/**  
 * @see  java.lang.String 
 * @see  #str 
 * @see  #str() 
 * @see  #main(String[]) 
 * @see  java.lang.Object#toString() 
 */  
 
public class TestJavaDoc  {   
private Stringstr; 
public voidstr(){   }
public staticvoid main(String[] args){   }
}
生成的文档的相关部分如下图:

Class TestJavaDoc

java.lang.Object
  └─TestJavaDoc
------------------------------------------------------
public class TestJavaDoc
extends java.lang.Object

See Also:
	String,str,str(),main(String[]),Object.toString()

2、@author、@version
这两个标记分别用于指明类的作者和版本。缺省情况下 javadoc 将其忽略，但命令行开关 -author 和 -version 可以修改这个功能，使其包含的信息被输出。

这两个标记的句法如下：   

@author 作者名  
@version 版本号   

其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效，生成的文档中只会显示
第一次使用 @version 指明的版本号。如下例

/**  
 * @author Fancy
 * @author Bird
 * @versionVersion 1.00
 * @versionVersion 2.00
 */ 
 
public class TestJavaDoc {}
 

生成文档的相关部分如图
Class TestJavaDoc

java.lang.Object
  └─TestJavaDoc
------------------------------------------------------
public class TestJavaDoc
extends java.lang.Object

Version:
	Version 1.00,Version 2.00
Auther:
	Fancy,Bird

3.@param、@return 和 @exception
这三个标记都是只用于方法的。@param 描述方法的参数，@return描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下： 

@param 参数名 参数说明
@return 返回值说明
@exception 异常类名说明 

每一个 @param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 @param 来描述。 

一个方法中只能用一个 @return，如果文档说明中列了多个@return，则 javadoc 编译时会发出警告，且只有第一个 @return 在生成的文档中有效。

方法可能抛出的异常应当用@exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每个 @exception 后面应有简述的异常类名，说
明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类名还是类全名。示例如下：

public class TestJavaDoc {  
 
/** 
 * @param n a switch 
 * @param b excrescent parameter 
 * @return true or false 
 * @return excrescent return 
 * @exception java.lang.Exception throw when switch is 1
 * @exception NullPointerException throw when parameter n is null 
 */ 
 
public boolean fun(Integer n) throws Exception { 
    switch (n.intValue()) { 
        case 0:  break;   
        case 1: throw new Exception("Test Only"); 
        default:  return false; 
      } 
      return true; 
   }
}
 

使用 javadoc 编译生成的文档相关部分如下图：

Method Detail

fun

public boolean fun(java.lang.Integer n)
           throws java.lang.Exception
   Parameters:
	   n - a switch
	   b - excrescent parameter
   Returns:
	   true or false
   Throws:
	   java.lang.Exception - throw when switch is 1
	   java.lang.NullPointerException - throw when parameter n in null

那么，我们该怎么在eclipse或myeclipse中设置这些标记模板呢？

设置注释模板的入口： Window->Preference->Java->Code Style->Code Template

下面是每个comment的设置模板，个人也可以自定义，但是团队开发的话，就需要统一遵循一个

1、文件(Files)注释标签：
/**
 * @Title ${file_name}
 * @package ${package_name}
 * @Description ${todo}
 * @auther ${user}
 * @Time ${date} ${time}
 * @Version
 */
2、类型(Types)注释标签（类的注释）：
/**
 * @ClassName ${file_name}
 * @Description ${todo}
 * @auther ${user}
 * @Time ${date} ${time}
 * 
 * ${tags}
 */
3、字段(Fields)注释标签：
/**
 * @Fidld1 ${field}:${todo}
 */
4、构造方法（constructor）标签：
/**
 * @Title ${file_name}
 * @Description ${todo}
 * 
 * ${tags} ${return_type}
 */
5、方法( Methods)标签：
/**
 * @Title ${enclosing_method}
 * @Description ${todo}
 * 
 * ${tags} ${return_type}
 */
6、覆盖方法(Overriding Methods)标签：
/**(non-Javadoc)
 * @Title ${enclosing_method}
 * @Description ${todo}
 * 
 * ${tags}
 * ${see_to_overridden
 */

7、代表方法(Delegate Methods)标签：
/**
 * ${tags}
 * ${see_to_target}
 */
8、getter方法标签：
/**
 * @return the ${bare_field_name}
 */
9、setter方法标签：
/**
 * @param ${param} the ${bare_field_name} to set
 */

